SEMCTL
Section: System Calls (2)
Index
Return to Main Contents
BSD mandoc
NetBSD
NAME
semctl
- semaphore control operations
SYNOPSIS
Fd #include <sys/types.h>
Fd #include <sys/ipc.h>
Fd #include <sys/sem.h>
Ft int
Fn semctl int semid int semnum int cmd union semun arg
DESCRIPTION
The
Fn semctl
system call provides a number of control operations on the semaphore specified
by
Fa semnum
and
Fa semid .
The operation to be performed is specified in
Fa cmd
(see below).
Fa arg
is a union of the following fields:
int val; /* value for SETVAL */
struct semid_ds *buf; /* buffer for IPC_{STAT,SET} */
u_short *array; /* array for GETALL & SETALL */
The
Bf -literal
semid_ds
Ef structure used in the IPC_SET and IPC_STAT commands is defined
as follows in
Aq Pa sys/sem.h :
struct semid_ds {
struct ipc_perm sem_perm; /* operation permissions */
struct sem *sem_base; /* semaphore set */
u_short sem_nsems; /* number of sems in set */
time_t sem_otime; /* last operation time */
time_t sem_ctime; /* last change time */
};
The
Bf -literal
ipc_perm
Ef structure used inside the
Bf -literal
semid_ds
Ef structure is defined in
Aq Pa sys/ipc.h
and looks like this:
struct ipc_perm {
ushort cuid; /* creator user id */
ushort cgid; /* creator group id */
ushort uid; /* user id */
ushort gid; /* group id */
ushort mode; /* r/w permission (see chmod(2)) */
ushort seq; /* sequence # (to generate unique msg/sem/shm id) */
key_t key; /* user specified msg/sem/shm key */
};
Fn semctl
provides the following operations:
- GETVAL
-
Return the value of the semaphore.
- SETVAL
-
Set the value of the semaphore to
arg.val
- GETPID
-
Return the pid of the last process that did an operation on this semaphore.
- GETNCNT
-
Return the number of processes waiting to acquire the semaphore.
- GETZCNT
-
Return the number of processes waiting for the value of the semaphore to
reach 0.
- GETALL
-
Return the values for all the semaphores associated with
Fa semid .
- SETALL
-
Set the values for all the semaphores that are associated with the semaphore
identifier
Fa semid
to the corresponding values in
arg.array
- IPC_STAT
-
Gather statistics about a semaphore and place the information in the
Bf -literal
semid_ds
Ef structure pointed to by
Fa arg.buf
(see above).
- IPC_SET
-
Set the value of the
sem_perm.uid
sem_perm.gid
and
sem_perm.mode
fields in the structure associated with the semaphore.
The values are taken from the corresponding fields in the structure
pointed to by
Fa arg.buf .
This operation can only be executed by the super-user, or a process that
has an effective user id equal to either
sem_perm.cuid
or
sem_perm.uid
in the data structure associated with the message queue.
- IPC_RMID
-
Remove the semaphores associated with
Fa semid
from the system and destroy the data structures associated with it. Only the
super-user or a process with an effective uid equal to the
sem_perm.cuid
or
sem_perm.uid
values in the data structure associated with the semaphore can do this.
The permission to read or change a message queue (see
semop(2))
is determined by the
sem_perm.mode
field in the same way as is
done with files (see
chmod(2)),
but the effective uid can match either the
sem_perm.cuid
field or the
sem_perm.uid
field, and the
effective gid can match either
sem_perm.cgid
or
sem_perm.gid
RETURN VALUES
For the GETVAL, GETPID, GETNCNT and GETZCNT operations,
Fn semctl
returns one of the values described above if successful. All other operations
will make
Fn semctl
return 0 if no errors occur. Otherwise -1 is returned and
errno
set to reflect the error.
ERRORS
Fn semctl
will fail if:
- Bq Er EPERM
-
Fa cmd
is equal to IPC_SET or IPC_RMID and the caller is not the super-user, nor does
the effective uid match either the
sem_perm.uid
or
sem_perm.cuid
fields of the data structure associated with the message queue.
- Bq Er EACCESS
-
The caller has no operation permission for this semaphore.
- Bq Er EINVAL
-
Fa semid
is not a valid message semaphore identifier.
cmd
is not a valid command.
- Bq Er EFAULT
-
Fa arg.buf
specifies an invalid address.
SEE ALSO
semop(2)
semget(2)
Index
- NAME
-
- SYNOPSIS
-
- DESCRIPTION
-
- RETURN VALUES
-
- ERRORS
-
- SEE ALSO
-
This document was created by
man2html,
using the manual pages.
Time: 16:28:59 GMT, April 18, 2022